<h1 id="errorobjects">Error objects</h1>

<h2>Property summary</h2>

<p>ECMAScript Error objects have very few standard properties, so many
ECMAScript implementations have added quite a few custom properties.
Duktape uses standard Error properties but also borrows the most useful
properties used by other implementations.  The number of "own" properties
of error objects is minimized to keep error objects as small as possible.</p>

<p>Error objects have the following properties (mostly inherited):</p>

<table>
<thead>
<tr><th>Property name</th><th>Compatibility</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td class="propname">name</td><td>standard</td><td>Name of error, e.g. <code>TypeError</code>, inherited</td></tr>
<tr><td class="propname">message</td><td>standard</td><td>Optional message of error, own property, empty message inherited if absent</td></tr>
<tr><td class="propname">fileName</td><td>Rhino</td><td>Filename related to error source, inherited accessor</td></tr>
<tr><td class="propname">lineNumber</td><td>Rhino</td><td>Linenumber related to error source, inherited accessor</td></tr>
<tr><td class="propname">stack</td><td>V8</td><td>Traceback as a multi-line human redable string, inherited accessor</td></tr>
</tbody>
</table>

<div class="note">
Assigning the most useful <code>fileName</code> and <code>lineNumber</code> is
somewhat complicated.  The related issues and current behavior are described in:
<a href="https://github.com/svaarala/duktape/blob/master/doc/error-objects.rst">error-objects.rst</a>.
</div>

<p>If Duktape is compiled with traceback support:</p>

<ul>
<li><code>stack</code>, <code>fileName</code>, and <code>lineNumber</code> are
    accessor properties inherited from <code>Error.prototype</code>.  You can
    override the properties by simply assigning over them: an inherited setter
    will capture the write but will create an own property as if a normal
    assignment was done.  This behavior was changed in Duktape 1.4.0 to better
    match other engines.</li>
<li>The raw traceback data needed by the accessor properties is stored in an internal
    property (<code>\x82Tracedata</code>) which is not normally accessible from
    ECMAScript code.</li>
</ul>

<p>If Duktape is compiled without traceback support:</p>
<ul>
<li>The <code>stack</code> accessor will be equivalent to
    <code>Error.prototype.toString()</code>, so that printing the stacktrace
    always produces a useful, human readable result.</li>
<li><code>fileName</code> and <code>lineNumber</code> will be own properties
    of the Error object.  You can override the properties using assignment.</li>
</ul>

<p>When error objects are created using the Duktape API from C code and the
caller does not give a format string for a <code>message</code>, the <code>message</code>
property is set to a numeric error code given in the API call.  The type of
<code>message</code> will be number in this case; normally error messages are
strings.   In minimized Duktape builds all errors generated internally by
Duktape use numeric error codes only.</p>

<p>An object is considered an "error object" if its internal prototype
chain contains the (original) <code>Error.prototype</code> object.  Only
objects matching this criteria get augmented with e.g. traceback data.</p>

<h2>Traceback</h2>

<p>The <code>stack</code> property is an accessor (setter/getter) property
which provides a printable traceback related to an error.  The traceback
reflects the call stack when the error object was created (not thrown).
Traceback data is automatically collected and added to an object:</p>
<ul>
<li>when an Error instance is constructed;</li>
<li>when an error is thrown from C code using the Duktape API;</li>
<li>when an error is thrown from inside Duktape.</li>
</ul>

<p>The data used to create the traceback is stored in an internal property
(<code>\x82Tracedata</code>), in an internal and version-dependent format
described
<a href="https://github.com/svaarala/duktape/blob/master/doc/error-objects.rst">error-objects.rst</a>.
You shouldn't access the traceback data directly.</p>

<p>The printable traceback format is intended to be human readable only.
You shouldn't rely on an exact traceback format as it may change between
versions (for example,
<a href="https://github.com/svaarala/duktape/pull/592">tracebacks were improved for the 1.5.0 release</a>).
As an example of the current traceback format, the program:</p>
<pre class="ecmascript-code">
// shortened from tests/ecmascript/test-dev-traceback-example.js
try {
    decodeURIComponent('%e1%a9%01');  // invalid utf-8
} catch (e) {
    print(e.stack);
}
</pre>

<p>would print something like:</p>
<pre>
URIError: invalid input
    at [anon] (duk_bi_global.c:343) internal
    at decodeURIComponent () native strict preventsyield
    at global (test.js:3) preventsyield
</pre>

<p>In builds where tracebacks are disabled, the <code>stack</code> accessor
will return the same value as calling <code>toString()</code> on the error
would.  This means you can always print <code>e.stack</code> and get a useful
output.</p>

<p>The most portable traceback printing approach is something like:</p>
<pre class="ecmascript-code">
try {
    decodeURIComponent('%e1%a9%01');  // invalid utf-8
} catch (e) {
    // Print stacktrace on at least Duktape and V8, or a standard error
    // string otherwise.
    print(e.stack || e);
}
</pre>

<p>An attempt to write to <code>stack</code> is captured by an inherited
setter which will create an own property as if a normal assignment was done.
This behavior differs from V8 where <code>stack</code> is an own property
of the Error instance.</p>

<h2 id="error-handlers">Error handlers (errCreate and errThrow)</h2>

<p>If <code>Duktape.errCreate</code> has been set, it is called right after
Duktape has added traceback information to an object, and can process the
error further or even replace the error value entirely.  The error handler
only gets called with <code>Error</code> instances, and its return value is
used as the final error value.  If the error handler throws an error, that
error replaces the original error.  The error handler is usually called only once
per error.  However, in corner cases related to constructors, the error handler
can be called multiple times for a single error value.</p>

<p>An error handler should avoid overwriting any properties already
present in an object, as that would be quite confusing for other code.
In general, an error handler should always avoid throwing an error, as that
error replaces the original error and would also be confusing.  As a specific
example, an error handler must not try to add a new property to a non-extensible
object, as that would cause a <code>TypeError</code>.</p>

<p>Below is an example error handler for adding a creation timestamp to
errors at their creation:</p>
<pre class="ecmascript-code">
Duktape.errCreate = function (e) {
    if (!(e instanceof Error)) {
        // this check is not really needed because errCreate only gets
        // called with Error instances
        return e;
    }
    if ('created' in e) {
        // already augmented or conflicting property present
        return e;
    }
    if (!Object.isExtensible(e)) {
        // object not extensible, don't try to add a new property
        return e;
    }
    e.created = new Date();
    return e;
}
</pre>

<p>To remove the handler, delete the property (setting it to e.g. <code>null</code>
does not work and causes a <code>TypeError</code> when Duktape attempts to
call the <code>null</code> value):</p>
<pre class="ecmascript-code">
// Remove error handler for error creation
delete Duktape.errCreate;
</pre>

<p>Similarly, if <code>Duktape.errThrow</code> has been set, it is called
right before an error is thrown, and can process or replace the error value.
Because ECMAScript allows any value type to be thrown, the error handler
may get called with arbitrary input values (not just <code>Error</code>
instances).  It may also be called more than once for the same value because
an error can be re-thrown multiple times.</p>

<p>For example, to add a throw timestamp (recording the first time the object
has been thrown) to errors:</p>
<pre class="ecmascript-code">
Duktape.errThrow = function (e) {
    if (!(e instanceof Error)) {
        // refuse to touch anything but Error instances
        return e;
    }
    if ('thrown' in e) {
        // already augmented or conflicting property present
        return e;
    }
    if (!Object.isExtensible(e)) {
        // object not extensible, don't try to add a new property
        return e;
    }
    e.thrown = new Date();
    return e;
}
</pre>

<p>Again, to remove the handler, delete the property:</p>
<pre class="ecmascript-code">
// Remove error handler for error throwing
delete Duktape.errThrow;
</pre>

<h2>Current limitations</h2>

<ul>
<li>There is no cause chain support.  Cause chains would be useful but there
    are no cause chains in ECMAScript, nor does there seem to be a de facto
    standard for them.</li>
<li>These is currently no way to access traceback elements programmatically in
    a version compatible manner.  However, you can access the <code>_Tracedata</code>
    hidden Symbol (<code>DUK_HIDDEN_SYMBOL("Tracedata")</code> from C code),
    but the raw tracedata format may change even in minor versions.  You can
    also overwrite the <code>.stack</code> property directly.</li>
<li>If an error is created with a non-constructor function call to a custom
    error class (<code>MyError('msg')</code> instead of <code>new MyError('msg')</code>)
    it won't get augmented with custom fields such as traceback data.  When
    called as a constructor custom errors inheriting from <code>Error</code> get
    augmented normally.  Built-in standard errors (like <code>TypeError</code>)
    always get augmented, even when created with a non-constructor function call
    (the tracebacks look slightly different depending on how the error is
    created, though).</li>
</ul>
